Getting started topic

Getting started

git_engine drives the installed git executable behind typed Dart contracts. An application chooses one engine where it wires its dependencies, then programs against interfaces, so the backend stays replaceable.

Choosing the engine at the composition root

Import package:git_engine/git_engine.dart for the contracts and value types. Import package:git_engine/process.dart only where the application constructs the process backend; take from it ProcessGitEngine and ProcessGitUploadPackService, then hold the constructed objects as contracts.

ProcessGitEngine implements GitRepositoryManager, GitFileClient and GitEngineRuntime. Its constructor names the git program, the environment layered over every command, the Windows long-path setting and the default command delay. Giving a runner together with any of those options is refused, because the runner already carries them.

GitEngineRuntime exposes the version facts a backend can report, through engineVersion and ensureMinimumVersion. A backend without a notion of version does not expose it. A timeout and an engine below the requested minimum stay domain refusals of git_engine.dart, so portable code catches them whatever the backend.

The process backend expects git 2.28 or newer. Its in-memory mergeTree needs git 2.38 or newer; an older installation cannot run that operation and the call is refused.

import 'package:git_engine/git_engine.dart';
import 'package:git_engine/process.dart';

Future<void> main() async {
  final ProcessGitEngine engine = ProcessGitEngine(
    executable: 'git',
    globalEnvironment: <String, String>{'GIT_CONFIG_NOSYSTEM': '1'},
    defaultTimeout: const Duration(minutes: 5),
  );
  final GitRepositoryManager repositories = engine;
  final GitFileClient client = engine;
  final GitEngineRuntime runtime = engine;
  print('${await runtime.engineVersion()}: $repositories $client');
}

Repository hierarchy

The hierarchy classifies a repository by the capabilities it has.

• GitRepository is the base contract. It assumes no index, no work tree and no filesystem, and every repository exposes its domain accessors: config, remotes, branches, tags, refs, revisions, history, objects, tree patches, merge and reference transactions. It also offers withTemporaryIndex and pruneWorktrees.
• GitIndexedRepository adds an active GitIndex and the patch operations that compare with or apply to that index. An indexed view derived from a bare repository no longer carries the bare marker.
• GitFileRepository adds disk facts: path, gitDir and the plain files of the git directory through GitDirectoryFiles.
• GitWorkingRepository implements both GitIndexedRepository and GitFileRepository. It is the only level with a work tree, adding toplevel, worktree, work-tree patches and in-place merge.
• GitBareRepository adds no operation. It marks a repository without a work tree, so a signature can require one; index work on it goes through an explicit index view.
• GitFileBareRepository combines bare storage with disk access. It is the type a server opens from disk.

Opening and creating

Opening reads the repository kind from git, so a directory that is not a repository fails immediately. open returns a GitFileRepository whose precise type is either GitWorkingRepository or GitFileBareRepository; openWorking and openBare return that precise type when the caller already knows it.

Creation fixes the type too: init returns a GitWorkingRepository with a work tree, and initBare returns a GitFileBareRepository. A missing target directory, missing parents included, is created; an existing empty directory is used as it stands. A directory that already holds files is refused before git runs unless allowOccupied hands it to git, which reinitializes an existing repository and keeps its data. initialBranch makes HEAD point at the named branch.

Cloning belongs to the client, not the manager: GitFileClient offers clone and cloneBare. The short runnable examples are example/local_repository.dart and example/bare_repository.dart.

import 'package:git_engine/git_engine.dart';
import 'package:git_engine/process.dart';

Future<void> main() async {
  final GitRepositoryManager repositories = ProcessGitEngine();
  final GitWorkingRepository working =
      await repositories.init('/srv/project', initialBranch: 'main');
  final GitFileRepository opened = await repositories.open(working.path);
  final GitFileBareRepository bare =
      await repositories.initBare('/srv/project.git', initialBranch: 'main');
  print('${opened.runtimeType} ${await bare.gitDir()}');
}

Libraries

git_engine

The package's backend-independent API: engine and repository contracts, value types, error hierarchy and server contracts.

Classes

GitApplyApplied

The patch applied cleanly, to the work tree, the index or both.

GitApplyConflicted

The patch applied with unresolved conflicts.

GitApplyRefused

The patch was refused; nothing was applied.

GitApplyResult

Outcome of applying a patch.

GitBareRepository

A bare GitRepository, typed explicitly.

GitBranch

A branch: its short name, the commit it points at, whether HEAD points at it, and the branch it tracks.

GitBranches

Branches of one repository: listing, creating, renaming, deleting and upstream tracking.

GitCommit

A commit object: its tree, parents, identities and message.

GitConfig

Local configuration of one repository.

GitConfigEntry

One key/value pair of a git configuration.

GitConflictRegion

One conflict block found in a work tree file.

GitDirectoryDrift

Differences between a GitDirectorySnapshot and the git directory as it stands now, reported file by file.

GitDirectoryFiles

Plain files of the git directory of one repository: capturing them, reporting what drifted since a capture, and writing a capture back.

GitDirectorySnapshot

A capture of the plain files of a git directory.

GitEngineRuntime

Facts about the version of an engine, independent of any backend.

GitFileBareRepository

A bare GitBareRepository stored on disk.

GitFileRepository

A GitRepository stored on disk.

GitHistory

History of one repository: ancestry, merge bases and path history.

GitHistoryReader

Walks the commit graph of one repository.

GitIdentity

Author or committer identity handed to git through environment variables.

GitIndex

Index of one repository: tree writing, unmerged entries and index removal.

GitIndexedPatches

Differences between a tree and the index of one repository, plus applying a patch to the index alone.

GitIndexedRepository

A GitRepository with an active index view.

GitLogCommit

One commit of a history walk: its object name and the complete commit.

GitLogEntry

One commit of a history walk: its object name and its subject.

GitMerge

Merging that needs neither an index nor a work tree: in-memory merges.

GitMergeCommit

A merge commit was created to fold the merged history in.

GitMergeConflicts

The merge could not be done automatically: the paths it lists were left with conflicts in the index and the work tree, and the merge stays in progress (MERGE_HEAD) until the caller resolves them or gives it up through GitWorkingMerge.abort.

GitMergeFastForward

Fast-forward: the current head moved forward onto the merged revision without a new commit.

GitMergeResult

Outcome of a merge, as one of the typed variants.

GitMergeStopped

A clean, non-fast-forward merge was staged but stopped before committing (noCommit): the index holds the merged state and MERGE_HEAD marks the merge as in progress, so the caller can commit it — or give it up through abort().

GitMergeTreeResult

Result of an in-memory merge (git merge-tree): the tree the merge would produce and the paths that conflict in it.

GitMergeUpToDate

The merged history was already part of the current head; nothing moved.

GitObjectReader

Read access to the objects of one repository, addressed by object name.

GitObjects

Objects, trees and commits of one repository, usable without touching the work tree.

GitObjectStore

Read and write access to the objects of one repository.

GitObjectWriter

Writes any object to a repository from its type and serialized content.

GitOid

A git object name: a 40-character (SHA-1) or 64-character (SHA-256) hexadecimal string.

GitPatches

Differences between two trees of one repository: changed paths, unified text diffs for display, and portable binary diffs.

GitRawObject

A git object read as stored: its type and its serialized content.

GitRef

A reference: its full name, e.g. refs/heads/main, and the object it points at.

GitRefReader

Read access to the references of one repository.

GitRefs

References of one repository: exact ref reads, symbolic refs and ref updates.

GitRefTransaction

A set of reference updates applied together, all or nothing.

GitRemotes

Remotes of one repository and their declaration: listing, adding, removing and renaming remotes, reading and writing their URLs.

GitRepository

Facade over one git repository, whatever its backend.

GitRepositoryManager

Manager role over repositories stored on disk: it opens and creates them.

GitRepositoryReader

Read-only view of one repository's stored data.

GitRepositoryWriter

Read and write view of the stored data of one repository.

GitRevisionResolver

Interprets git revision expressions (HEAD~2, main^{tree}…).

GitRevisions

Revision expressions of one repository.

GitStatusEntry

One entry of the work tree status, as reported by git status.

GitTag

An annotated tag object: the object it points at, its name, the tagger and the message.

GitTagRef

A tag reference: its short name, the object the reference names and the final object that object resolves to.

GitTags

Tags of one repository: listing, creating and deleting.

GitTree

A tree object: its object name and the entries it lists.

GitTreeEntry

One entry of a tree object: a blob, a subtree or a gitlink.

GitUnmergedEntry

One stage of a path left unmerged in the index.

GitWorkingMerge

Merging into a work tree: fast-forwards, merge commits, conflicted merges and the in-progress merge state with its abort.

GitWorkingPatches

Differences between the index and the work tree of one repository, plus applying a patch to the work tree.

GitWorkingRepository

A GitFileRepository with a work tree and an active index view.

GitWorktree

Work tree and index of one repository: status, staging, reset, cleaning, checkout, ignore checks and commits.

ProcessGitEngine

GitRepositoryManager, GitFileClient and GitEngineRuntime that talk to the real git executable through a ProcessGitRunner (or any GitRunner handed to the constructor).

Enums

GitArchiveFormat

Format of an archive streamed by GitObjects.archive.

GitChangeKind

How a path changed between the two sides of a comparison.

GitFileState

State of a path reported by git status, on one side of the index.

GitMergeMode

Which merges GitWorkingMerge.merge is allowed to perform.

GitObjectType

Kind of an object stored in a git repository.

GitResetMode

How git reset moves HEAD, the index and the work tree.

GitTagFetch

Which tags a fetch brings into the repository.